sleeper API Docs.txt•22.9 kB
Introduction
The Sleeper API is a read-only HTTP API that is free to use and allows access to a user's leagues, drafts, and rosters.
No API Token is necessary, as you cannot modify contents via this API.
Be mindful of the frequency of calls. A general rule is to stay under 1000 API calls per minute, otherwise, you risk being IP-blocked.
User
To fetch a user object, use this code:
# With shell, you can just curl the username or user_id
curl "https://api.sleeper.app/v1/user/<username>"
curl "https://api.sleeper.app/v1/user/<user_id>"
You will get a JSON response that looks something like this:
{
"username": "sleeperuser",
"user_id": "12345678",
"display_name": "SleeperUser",
"avatar": "cc12ec49965eb7856f84d71cf85306af"
}
We do not perform authentication as our API is read-only and only contains league information.
Via the user resource, you can GET the user object by either providing the username or user_id of the user.
GET https://api.sleeper.app/v1/user/<username>
GET https://api.sleeper.app/v1/user/<user_id>
Keep in mind that the username of a user can change over time, so if you are storing information, you'll want to hold onto the user_id.
Avatars
Users and leagues have avatar images. There are thumbnail and full-size images for each avatar.
Full size URL
https://sleepercdn.com/avatars/<avatar_id>
Thumbnail URL
https://sleepercdn.com/avatars/thumbs/<avatar_id>
Leagues
Get all leagues for user
curl "https://api.sleeper.app/v1/user/<user_id>/leagues/nfl/2018"
The above command returns JSON structured like this:
[
{
"total_rosters": 12,
"status": "pre_draft", // can also be "drafting", "in_season", or "complete"
"sport": "nfl",
"settings": { settings object },
"season_type": "regular",
"season": "2018",
"scoring_settings": { scoring_settings object },
"roster_positions": [ roster positions array ],
"previous_league_id": "198946952535085056",
"name": "Sleeperbot Friends League",
"league_id": "289646328504385536",
"draft_id": "289646328508579840",
"avatar": "efaefa889ae24046a53265a3c71b8b64"
},
{
"total_rosters": 12,
"status": "in_season",
"sport": "nfl",
"settings": { settings object },
"season_type": "regular",
"season": "2018",
"scoring_settings": { scoring_settings object },
"roster_positions": [ roster positions array ],
"previous_league_id": "198946952535085056",
"name": "Sleeperbot Dynasty",
"league_id": "289646328504385536",
"draft_id": "289646328508579840",
"avatar": "efaefa889ae24046a53265a3c71b8b64"
},
]
This endpoint retrieves all leagues.
HTTP Request
GET https://api.sleeper.app/v1/user/<user_id>/leagues/<sport>/<season>
URL Parameters
Parameter Description
user_id The numerical ID of the user.
sport We only support "nfl" right now.
season Season can be 2017, 2018, etc...
Get a specific league
curl "https://api.sleeper.app/v1/league/<league_id>"
The above command returns JSON structured like this:
{
"total_rosters": 12,
"status": "in_season",
"sport": "nfl",
"settings": { settings object },
"season_type": "regular",
"season": "2018",
"scoring_settings": { scoring_settings object },
"roster_positions": [ roster positions array ],
"previous_league_id": "198946952535085056",
"name": "Sleeperbot Dynasty",
"league_id": "289646328504385536",
"draft_id": "289646328508579840",
"avatar": "efaefa889ae24046a53265a3c71b8b64"
}
This endpoint retrieves a specific league.
HTTP Request
GET https://api.sleeper.app/v1/league/<league_id>
URL Parameters
Parameter Description
league_id The ID of the league to retrieve
Getting rosters in a league
curl "https://api.sleeper.app/v1/league/<league_id>/rosters"
The above command returns JSON structured like this:
[
{
"starters": ["2307", "2257", "4034", "147", "642", "4039", "515", "4149", "DET"],
"settings": {
"wins": 5,
"waiver_position": 7,
"waiver_budget_used": 0,
"total_moves": 0,
"ties": 0,
"losses": 9,
"fpts_decimal": 78,
"fpts_against_decimal": 32,
"fpts_against": 1670,
"fpts": 1617
},
"roster_id": 1,
"reserve": [],
"players": ["1046", "138", "147", "2257", "2307", "2319", "4034", "4039", "4040", "4149", "421", "515", "642", "745", "DET"],
"owner_id": "188815879448829952",
"league_id": "206827432160788480"
},
...
]
This endpoint retrieves all rosters in a league.
HTTP Request
GET https://api.sleeper.app/v1/league/<league_id>/rosters
URL Parameters
Parameter Description
league_id The ID of the league to retrieve rosters from
Getting users in a league
curl "https://api.sleeper.app/v1/league/<league_id>/users"
The above command returns JSON structured like this:
[
{
"user_id": "<user_id>",
"username": "<username>",
"display_name": "<display_name>",
"avatar": "1233456789",
"metadata": {
"team_name": "Dezpacito"
},
"is_owner": true // is commissioner (there can be multiple commissioners)
},
...
]
This endpoint retrieves all users in a league.
This also includes each user's display_name, avatar, and their metadata which sometimes includes a nickname they gave their team.
HTTP Request
GET https://api.sleeper.app/v1/league/<league_id>/users
URL Parameters
Parameter Description
league_id The ID of the league to retrieve rosters from
Getting matchups in a league
curl "https://api.sleeper.app/v1/league/<league_id>/matchups/<week>"
The above command returns JSON structured like this:
[
{
"starters": ["421", "4035", "3242", "2133", "2449", "4531", "2257", "788", "PHI"],
"roster_id": 1,
"players": ["1352", "1387", "2118", "2133", "2182", "223", "2319", "2449", "3208", "4035", "421", "4881", "4892", "788", "CLE"],
"matchup_id": 2,
"points": 20.0 // total points for team based on league settings
"custom_points": null // if commissioner overrides points manually
},
...
]
This endpoint retrieves all matchups in a league for a given week. Each object in the list represents one team. The two teams with the same matchup_id match up against each other.
The starters is in an ordered list of player_ids, and players is a list of all player_ids in this matchup.
The bench can be deduced by removing the starters from the players field.
HTTP Request
GET https://api.sleeper.app/v1/league/<league_id>/matchups/<week>
URL Parameters
Parameter Description
league_id The ID of the league to retrieve matchups from
week The week these matchups take place
Getting the playoff bracket
curl "https://api.sleeper.app/v1/league/<league_id>/winners_bracket"
curl "https://api.sleeper.app/v1/league/<league_id>/losers_bracket"
The above command returns JSON structured like this:
[
{r: 1, m: 1, t1: 3, t2: 6, w: null, l: null},
{r: 1, m: 2, t1: 4, t2: 5, w: null, l: null},
{r: 2, m: 3, t1: 1, t2: null, t2_from: {w: 1}, w: null, l: null},
{r: 2, m: 4, t1: 2, t2: null, t2_from: {w: 2}, w: null, l: null},
{r: 2, m: 5, t1: null, t2: null, t1_from: {l: 1}, t2_from: {l: 2}, w: null, l: null, p: 5},
{r: 3, m: 6, t1: null, t2: null, t1_from: {w: 3}, t2_from: {w: 4}, w: null, l: null, p: 1},
{r: 3, m: 7, t1: null, t2: null, t1_from: {l: 3}, t2_from: {l: 4}, w: null, l: null, p: 3}
]
This endpoint retrieves the playoff bracket for a league for 4, 6, and 8 team playoffs.
Each row represents a matchup between 2 teams.
Field Type Description
r int The round for this matchup, 1st, 2nd, 3rd round, etc.
m int The match id of the matchup, unique for all matchups within a bracket.
t1 int The roster_id of a team in this matchup OR {w: 1} which means the winner of match id 1
t2 int The roster_id of the other team in this matchup OR {l: 1} which means the loser of match id 1
w int The roster_id of the winning team, if the match has been played.
l int The roster_id of the losing team, if the match has been played.
t1_from object Where t1 comes from, either winner or loser of the match id, necessary to show bracket progression.
t2_from object Where t2 comes from, either winner or loser of the match id, necessary to show bracket progression.
HTTP Request
GET https://api.sleeper.app/v1/league/<league_id>/winners_bracket
GET https://api.sleeper.app/v1/league/<league_id>/loses_bracket
URL Parameters
Parameter Description
league_id The ID of the league to retrieve matchups from
Get transactions
curl "https://api.sleeper.app/v1/league/<league_id>/transactions/<round>"
The above command returns JSON structured like this:
[
{
"type": "trade",
"transaction_id": "434852362033561600",
"status_updated": 1558039402803,
"status": "complete",
"settings": null, // trades do not use this field
"roster_ids": [2, 1], // roster_ids involved in this transaction
"metadata": null,
"leg": 1, // in football, this is the week
"drops": null,
"draft_picks": [ // picks that were traded
{
"season": "2019",// the season this draft pick belongs to
"round": 5, // which round this draft pick is
"roster_id": 1, // original owner's roster_id
"previous_owner_id": 1, // previous owner's roster id (in this trade)
"owner_id": 2, // the new owner of this pick after the trade
},
{
"season": "2019",
"round": 3,
"roster_id": 2,
"previous_owner_id": 2,
"owner_id": 1,
}
],
"creator": "160000000000000000", // user id who initiated the transaction
"created": 1558039391576,
"consenter_ids": [2, 1], // roster_ids of the people who agreed to this transaction
"adds": null
"waiver_budget": [ // roster_id 2 sends 55 FAAB dollars to roster_id 3
{
"sender": 2,
"receiver": 3,
"amount": 55
}
],
},
{
"type": "free_agent", // could be waiver or trade as well
"transaction_id": "434890120798142464",
"status_updated": 1558048393967,
"status": "complete",
"settings": null, // could be {'waiver_bid': 44} if it's FAAB waivers
"roster_ids": [1], // roster_ids involved in this transaction
"metadata": null, // can contain notes in waivers like why it didn't go through
"leg": 1,
"drops": {
"1736": 1 // player id 1736 dropped from roster_id 1
},
"draft_picks": [],
"creator": "160000000000000000",
"created": 1558048393967,
"consenter_ids": [1], // the roster_ids who agreed to this transaction
"adds": {
"2315": 1 // player id 2315 added to roster_id 1
...
},
"waiver_budget": [] // this used for trades only involving FAAB
},
...
]
This endpoint retrieves all free agent transactions, waivers and trades.
HTTP Request
GET https://api.sleeper.app/v1/league/<league_id>/transactions/<round>
URL Parameters
Parameter Description
league_id The ID of the draft to retrieve picks for
round The week you want to pull from
Get traded picks
curl "https://api.sleeper.app/v1/league/<league_id>/traded_picks"
The above command returns JSON structured like this:
[
{
"season": "2019", // which season the pick is for
"round": 5, // which round the pick is
"roster_id": 1, // roster_id of ORIGINAL owner
"previous_owner_id": 1, // roster_id of the previous owner
"owner_id": 2, // roster_id of current owner
},
{
"season": "2020", // which season the pick is for
"round": 3, // which round the pick is
"roster_id": 2, // roster_id of original owner
"previous_owner_id": 2, // roster_id of previous owner
"owner_id": 1, // roster_id of current owner
},
...
]
This endpoint retrieves all traded picks in a league, including future picks.
HTTP Request
GET https://api.sleeper.app/v1/league/<league_id>/traded_picks
URL Parameters
Parameter Description
league_id The ID of the league to retrieve traded picks for
Get NFL state
curl "https://api.sleeper.app/v1/state/nfl"
The above command returns JSON structured like this:
{
"week": 2, // week
"season_type": "regular", // pre, post, regular
"season_start_date": "2020-09-10", // regular season start
"season": "2020", // current season
"previous_season": "2019",
"leg": 2, // week of regular season
"league_season": "2021", // active season for leagues
"league_create_season": "2021", // flips in December
"display_week": 3 // Which week to display in UI, can be different than week
}
This endpoint returns information about the current state for any sport.
HTTP Request
GET https://api.sleeper.app/v1/state/<sport>
URL Parameters
Parameter Description
sport nfl, nba, lcs, etc...
Drafts
Get all drafts for user
curl "https://api.sleeper.app/v1/user/<user_id>/drafts/nfl/2018"
The above command returns JSON structured like this:
[
{
"type": "snake",
"status": "complete",
"start_time": 1515700800000,
"sport": "nfl",
"settings": {
"teams": 6,
"slots_wr": 2,
"slots_te": 1,
"slots_rb": 2,
"slots_qb": 1,
"slots_k": 1,
"slots_flex": 2,
"slots_def": 1,
"slots_bn": 5,
"rounds": 15,
"pick_timer": 120
},
"season_type": "regular",
"season": "2017",
"metadata": {
"scoring_type": "ppr",
"name": "My Dynasty",
"description": ""
},
"league_id": "257270637750382592",
"last_picked": 1515700871182,
"last_message_time": 1515700942674,
"last_message_id": "257272036450111488",
"draft_order": null,
"draft_id": "257270643320426496",
"creators": null,
"created": 1515700610526
},
...
]
This endpoint retrieves all drafts by a user.
HTTP Request
GET https://api.sleeper.app/v1/user/<user_id>/drafts/<sport>/<season>
URL Parameters
Parameter Description
user_id The numerical ID of the user.
sport We only support "nfl" right now.
season Season can be 2017, 2018, etc...
Get all drafts for a league
curl "https://api.sleeper.app/v1/league/<league_id>/drafts"
The above command returns JSON structured like this:
[
{
"type": "snake",
"status": "complete",
"start_time": 1515700800000,
"sport": "nfl",
"settings": {
"teams": 6,
"slots_wr": 2,
"slots_te": 1,
"slots_rb": 2,
"slots_qb": 1,
"slots_k": 1,
"slots_flex": 2,
"slots_def": 1,
"slots_bn": 5,
"rounds": 15,
"pick_timer": 120
},
"season_type": "regular",
"season": "2017",
"metadata": {
"scoring_type": "ppr",
"name": "My Dynasty",
"description": ""
},
"league_id": "257270637750382592",
"last_picked": 1515700871182,
"last_message_time": 1515700942674,
"last_message_id": "257272036450111488",
"draft_order": null,
"draft_id": "257270643320426496",
"creators": null,
"created": 1515700610526
},
...
]
This endpoint retrieves all drafts for a league. Keep in mind that a league can have multiple drafts, especially dynasty leagues.
Drafts are sorted by most recent to earliest. Most leagues should only have one draft.
HTTP Request
GET https://api.sleeper.app/v1/league/<league_id>/drafts
URL Parameters
Parameter Description
league_id The ID of the league for which you are trying to retrieve drafts.
Get a specific draft
curl "https://api.sleeper.app/v1/draft/<draft_id>"
The above command returns JSON structured like this:
{
"type": "snake",
"status": "complete",
"start_time": 1515700800000,
"sport": "nfl",
"settings": {
"teams": 6,
"slots_wr": 2,
"slots_te": 1,
"slots_rb": 2,
"slots_qb": 1,
"slots_k": 1,
"slots_flex": 2,
"slots_def": 1,
"slots_bn": 5,
"rounds": 15,
"pick_timer": 120
},
"season_type": "regular",
"season": "2017",
"metadata": {
"scoring_type": "ppr",
"name": "My Dynasty",
"description": ""
},
"league_id": "257270637750382592",
"last_picked": 1515700871182,
"last_message_time": 1515700942674,
"last_message_id": "257272036450111488",
// this is the user_id to draft slot mapping
"draft_order": {
"12345678": 1,
"23434332": 2,
...
},
// this is the draft slot to roster_id mapping
// leagues have rosters, which have roster_ids
// this means draft slot 1 (column 1) will go to roster 10, slot 2 will go to roster_id 3, etc
"slot_to_roster_id": {
"1": 10,
"2": 3,
"3": 5
},
"draft_id": "257270643320426496",
"creators": null,
"created": 1515700610526
}
This endpoint retrieves a specific draft.
HTTP Request
GET https://api.sleeper.app/v1/draft/<draft_id>
URL Parameters
Parameter Description
draft_id The ID of the draft to retrieve
Get all picks in a draft
curl "https://api.sleeper.app/v1/draft/<draft_id>/picks"
The above command returns JSON structured like this:
[
{
"player_id": "2391",
"picked_by": "234343434", // user_id this pick will go to (not all leagues have users in every slot, this can be "")
"roster_id": "1", // roster_id this pick will go to
"round": 5,
"draft_slot": 5, // which column this is on the draftboard
"pick_no": 1,
"metadata": {
"team": "ARI",
"status": "Injured Reserve",
"sport": "nfl",
"position": "RB",
"player_id": "2391",
"number": "31",
"news_updated": "1513007102037",
"last_name": "Johnson",
"injury_status": "Out",
"first_name": "David"
},
"is_keeper": null,
"draft_id": "257270643320426496"
},
{
"player_id": "1408",
"picked_by": "234343434", // user_id this pick will go to (not all leagues have users in every slot, this can be "")
"roster_id": "1", // roster_id this pick will go to
"round": 5,
"draft_slot": 6,
"pick_no": 2,
"metadata": {
"team": "PIT",
"status": "Active",
"sport": "nfl",
"position": "RB",
"player_id": "1408",
"number": "26",
"news_updated": "1515698101257",
"last_name": "Bell",
"injury_status": "",
"first_name": "Le'Veon"
},
"is_keeper": null,
"draft_id": "257270643320426496"
},
{
"player_id": "536",
"picked_by": "667279356739584",
"pick_no": 3,
"metadata": {
"team": "PIT",
"status": "Active",
"sport": "nfl",
"position": "WR",
"player_id": "536",
"number": "84",
"news_updated": "1515673801292",
"last_name": "Brown",
"injury_status": "Probable",
"first_name": "Antonio"
},
"is_keeper": null,
"draft_id": "257270643320426496"
},
...
]
This endpoint retrieves all picks in a draft.
HTTP Request
GET https://api.sleeper.app/v1/draft/<draft_id>/picks
URL Parameters
Parameter Description
draft_id The ID of the draft to retrieve picks for
Get traded picks in a draft
curl "https://api.sleeper.app/v1/draft/<draft_id>/traded_picks"
The above command returns JSON structured like this:
[
{
"season": "2019",
"round": 5, // which round the pick is
"roster_id": 1, // roster_id of ORIGINAL owner
"previous_owner_id": 1, // roster_id of the previous owner
"owner_id": 2, // roster_id of current owner
},
{
"season": "2019",
"round": 3, // which round the pick is
"roster_id": 2, // roster_id of original owner
"previous_owner_id": 2, // roster_id of previous owner
"owner_id": 1, // roster_id of current owner
},
...
]
This endpoint retrieves all traded picks in a draft.
HTTP Request
GET https://api.sleeper.app/v1/draft/<draft_id>/traded_picks
URL Parameters
Parameter Description
draft_id The ID of the draft to retrieve picks for
Players
Fetch all players
To fetch all players, use this code:
curl "https://api.sleeper.app/v1/players/nfl"
You will get a JSON response that looks something like this:
{
"3086": {
"hashtag": "#TomBrady-NFL-NE-12",
"depth_chart_position": 1,
"status": "Active",
"sport": "nfl",
"fantasy_positions": ["QB"],
"number": 12,
"search_last_name": "brady",
"injury_start_date": null,
"weight": "220",
"position": "QB",
"practice_participation": null,
"sportradar_id": "",
"team": "NE",
"last_name": "Brady",
"college": "Michigan",
"fantasy_data_id":17836,
"injury_status":null,
"player_id":"3086",
"height": "6'4\"",
"search_full_name": "tombrady",
"age": 40,
"stats_id": "",
"birth_country": "United States",
"espn_id": "",
"search_rank": 24,
"first_name": "Tom",
"depth_chart_order": 1,
"years_exp": 14,
"rotowire_id": null,
"rotoworld_id": 8356,
"search_first_name": "tom",
"yahoo_id": null
},
...
}
Please use this call sparingly, as it is intended only to be used once per day at most to keep your player IDs updated. The average size of this query is 5MB.
Since rosters and draft picks contain Player IDs which look like "1042", "2403", "CAR", etc, you will need to know what those IDs map to. The /players call provides you the map necessary to look up any player.
You should save this information on your own servers as this is not intended to be called every time you need to look up players due to the filesize being close to 5MB in size. You do not need to call this endpoint more than once per day.
GET https://api.sleeper.app/v1/players/nfl
Trending Players
To get a list of trending players based on add/drop activity:
curl "https://api.sleeper.app/v1/players/nfl/trending/add"
You will get a JSON response that looks something like this:
[
{
"player_id": "1111", // the player_id
"count": 45 // number or adds
},
...
]
Want to embed this on your app? Copy the code below:
<iframe src="https://sleeper.app/embed/players/nfl/trending/add?lookback_hours=24&limit=25" width="350" height="500" allowtransparency="true" frameborder="0"></iframe>
Please give attribution to Sleeper you are using our trending data. If you'd like to embed our trending list on your website or blog, please use the embed code on the right.
You can use this endpoint to get a list of trending players based on adds or drops in the past 24 hours.
GET https://api.sleeper.app/v1/players/<sport>/trending/<type>?lookback_hours=<hours>&limit=<int>
URL Parameters
Parameter Description
sport The sport, such as nfl
type Either add or drop
lookback_hours Number of hours to look back (default is 24) - optional
limit Number of results you want, (default is 25) - optional
Errors
The Sleeper API uses the following error codes:
Code Meaning
400 Bad Request -- Your request is invalid.
404 Not Found -- The specified kitten could not be found.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.